Technotes

Download Acrobat file (16K)

Download AppleWorks file (44K)

Technote 1058

JULY 1996

For some time now, Apple developers have been confused by the 'ptyp' (paper type) resource in QuickDraw GX. This is a result of sparse documentation and problems with QuickDraw GX's use of this resource. This Technote :

• discusses the 'ptyp' resource in detail
• shows how to calculate your page and paper rectangles for the resource
• discusses how to set your paper type as the default paper type
• gives an overview of the known bugs and their workarounds
• gives a brief overview of how to create a paper type with QuickDraw GX's Paper Type Editor and how to alter those paper types into 'ptyp' resources.

CONTENTS

• The 'ptyp' Resource Defined
  
• Calculating the Page and Paper Rectangle Values
  
• Making Your Paper Type the Default Type
  
• Making Sure Your New Paper Type Appears in the Print Dialog
  
• The Paper Type Editor
  
• Summary
  

The 'ptyp' Resource Defined

The following section introduces you to the internal structure of the 'ptyp' resource.

Definition

The paper type resource, of type gxPaperTypeType, provides you with a mechanism to create paper types that are customized for their QuickDraw GX printer driver. This resource is optional.

The structure of paper type resource is:

'ptyp'	Type
Paper Type Name	pstring
Page Rectangle	gxRectangle
Paper Rectangle	gxRectangle
Base Paper	longint
Creator Type	literal longint
Unit of Measure	byte
PaperType Style flags	unsigned bitstring
Default flags	unsigned bitstring
Reserved flags	unsigned bitstring
Embedded Collection	longint
array- Collection Items
- Collection tag	longint
- Collection id	longint
- Collection attribute bits- lock	Boolean
- Collection attribute bits- persistent	Boolean
- Reserved attribute bits	unsigned bitstring
- User attribute bits	unsigned bitstring
- Data	wstring

The paper type resource consists of entries, flags and one or more collection items:

• Paper Type Name: The name to display in the paper type list presented to the user in the page set-up dialog.
• Page Rectangle: The page rectangle measurements of the paper type.
• Paper Rectangle: The paper rectangle measurements of the paper type.
• Base Paper: The base paper type from which this new paper type is derived.

  Constant	Value
  unknownBase	0
  usLetterBase	1
  usLegalBase	2
  a4LetterBase	3
  b5LetterBase	4
  tabloidBase	5

• Creator Type: The creator of the paper type.
• Unit of Measure: Unit of measure the paper is in.

  Constant	Value
  pica	0
  mm	1
  inch	2

• PaperType Style flags: Notates whether this paper type is for old, new or both old and new print dialogs.

  Constant	Value
  newStylePaperType	1
  oldStylePaperType	2
  oldAndNewStylePaperType	3

- Collection tag:

A collection tag is a four-character identifier that, in conjunction with the collection ID, uniquely identifies the collection item.

- Collection ID:

A collection ID is a long value that, in conjunction with the collection tag, uniquely identifies the collection item.

- Collection attribute bits- lock:

locks the item down to avoid replacement.

- Collection attribute bits- persistent:

identifies whether or not to flatten this item when flattening the collection.

- Reserved attribute bits:

bits that are reserved internally.

- User attribute bits:

bits you can define for purposes suitable to your needs.

- Data:

contains the actual data of the collection item.

The structure of the 'ptyp' resource can be seen in GXPrintingResTypes.r on the Developer CD Series: Mac OS SDK Edition.

Calculating the Page and Paper Rectangle Values

1. Convert inches to pixels. Multiply 8.10667 by 72 (for 72 dpi). The result is 583.68005 pixels.
2. Convert the pixel value to hexadecimal to get 0x0247AE18.

   For the vertical value, repeat steps 1 and 2, multiplying 10.7867 inches instead of 8.10667.

Once you are finished with the calculations, the top portion of your 'ptyp' resource will look like the following:

resource gxPaperTypeType (gxPrintingDriverBaseID+1, "US Letter",
kResAttributes)
{

"US Letter",

/*page rectangle*/
0x00000000, 	/*0.0*/
0x00000000, 	/*0.0*/
0x0247AE18, 	/*8.10667*/
0x0308A3DC, 	/*10.7867*/

/*paper rectangle*/
0xFFF1D70C, 	/*-0.196666*/
0xFFF870A8, 	/*-0.104999*/
0x0247AE18, 	/*8.30333*/
0x0308A3DC, 	/*10.895*/

usLetterType,
kCreatorType,

inch,
etc.
}

Making Your Paper Type the Default Type

The Flag

If QuickDraw GX encounters more than one paper type in your driver with the isDefaultPaperType flag set, QuickDraw GX will either fail or choose the first paper type it "sees." In either case, it is not a good idea to have more than one paper type in your resource fork with the isDefaultPaperType flag set.

A Known bug

Several Workarounds

Workaround #1:

If you are defaulting to a non-standard papertype, such as Letterhead, Stationery or Three-hole Punch, the best workaround is to remove that papertype from the Extensions folder.

Workaround #2:

If you are defaulting to another standard papertype, the easiest thing you can do is to open your driver with ResEdit and either remove or edit the 'ptyp' resource for the incorrectly matched papertype.

Currently, these are the only known workarounds. Neither may be very user-friendly, but in both cases, they ought to force the driver to default to the correct papertype.

Making Sure Your New Paper Type Appears in the Print Dialog

The Paper Type Editor

Developers are usually interested in how they can use the Paper Type Editor to create paper type resources to ship with their QuickDraw GX printer drivers. In order to convert the paper type that the Paper Type Editor creates into a 'ptyp' resource, you need to DeRez the paper type, set the oldAndNewStylePaperType flag (and the isDefaultPaperType flag if necessary), Rez it back and copy it into your printer driver's resource fork. After restarting, the paper types should correctly appear in your QuickDraw GX printer driver.

Summary

Further References

• Inside Macintosh: QuickDraw GX Printing Extensions and Drivers.
• Inside Macintosh: QuickDraw GX Printing.
• Inside Macintosh: QuickDraw GX Environment and Utilities.
• Macintosh Technical Note 1028.
• Developer CD Series: Mac OS SDK Edition: Development Kits (Disc I): Interfaces and Libraries: Interfaces: RIncludes:GXPrintingResTypes.r.